/*
 * Copyright 2011 The Rusted Roof, LLC.
 *
 *    Licensed under the Apache License, Version 2.0 (the "License");
 *    you may not use this file except in compliance with the License.
 *    You may obtain a copy of the License at
 *
 *        http://www.apache.org/licenses/LICENSE-2.0
 *
 *    Unless required by applicable law or agreed to in writing, software
 *    distributed under the License is distributed on an "AS IS" BASIS,
 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *    See the License for the specific language governing permissions and
 *    limitations under the License.
 */

package org.proteusframework.platformservice;

import org.proteusframework.core.api.IProteusConstants;
import org.proteusframework.core.api.IRuntimeConfiguration;
import org.proteusframework.core.api.model.INamespace;
import org.proteusframework.core.api.model.IPlugin;

/**
 * Specialized type of an {@link org.proteusframework.core.api.IRuntimeConfiguration} that depicts a platform service
 * engine. Platform runtime configurations expressly provide an application-wide service configuration that is
 * intrinsically integrated into the Proteus Framework itself.
 *
 * @see IServicePlugin
 */
public interface IExtendedRuntimeConfiguration extends IRuntimeConfiguration
{
    /**
     * Proteus Framework prefix used to differentiate between stock and custom platform services.
     */
    public static final String PROTEUS_SERVICE_KEY_PREFIX = IProteusConstants.NAMESPACE + ".service.";

    /**
     * Key used inside of a /proteus.properties file to define the app config service provider class.
     */
    public static final String KEY_APP_CONFIG_SERVICE = PROTEUS_SERVICE_KEY_PREFIX + "ApplicationConfiguration";

    /**
     * Key used inside of a /proteus.properties file to define the lifecycle service provider class.
     */
    public static final String KEY_LIFECYCLE_SERVICE = PROTEUS_SERVICE_KEY_PREFIX + "Lifecycle";

    /**
     * Key used inside of a /proteus.properties file to define the persistence service provider class.
     */
    public static final String KEY_PERSISTENCE_SERVICE = PROTEUS_SERVICE_KEY_PREFIX + "Persistence";

    /**
     * Key used inside of a /proteus.properties file to define the messaging service provider class.
     */
    public static final String KEY_MESSAGE_SERVICE = PROTEUS_SERVICE_KEY_PREFIX + "Message";

    /**
     * Key used inside of a /proteus.properties file to define the theme service provider class.
     */
    public static final String KEY_THEME_SERVICE = PROTEUS_SERVICE_KEY_PREFIX + "Theme";

    /**
     * Request the active instance of the specified platform service, if the service is installed in the given
     * runtime environment.
     *
     * @param serviceClassification Platform service to locate
     * @param expectedInterface     Expected interface of the given platform service
     * @return Active instance of the specified platform service
     * @throws ServiceNotInstalledException When the specified platform service is not installed within the current
     *                                      runtime engine
     */
    <T extends IServicePlugin> T getPlatformService(ServiceClassification serviceClassification, Class<T> expectedInterface)
            throws ServiceNotInstalledException;
}
